import { Callout } from 'nextra/components'
import BadgeGroup, { UniverTypes } from '@/components/BadgeGroup'
import ReactLive from '@/components/ReactLive'

# Univer Doc API

<BadgeGroup values={[UniverTypes.DOC]} value={UniverTypes.DOC} />

## 概念

Univer 文档提供专业级文档排版能力，相关概念会尽可能与 Word 保持一致。

## 文档

命令系统中 `unitId` 对应的是文档的唯一标识，文档没有 `subUnitId` 。

文档的文本内容存储在 `body.dataStream` 字符串中，这个字符串不包含样式信息。

样式信息单独存储在另外的数据结构中，并通过下标索引与文本内容关联。

对于换行、分页、章节、段落、表格等元素， 在文本内容中使用不同的特殊字符来标记，这些特殊字符在渲染时被转换为对应的元素。

<Callout type="info" emoji="ℹ️">
  想要进一步了解文档的数据结构设计吗？推荐阅读 [Univer 文档架构及模块设计](/blog/post/univer-doc-architecture) 和  [Univer 文档排版设计初探](/blog/post/doc-typesetting-design)。
</Callout>

### 创建文档

`univer.createUnit(UniverInstanceType.UNIVER_DOC, {})` 方法会创建并返回 `DocumentDataModel` 对象。

下面例子，传入空对象，创建一个空白文档。

export const code = `const univer = new Univer({
  theme: defaultTheme,
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: zhCN,
  },
});

univer.registerPlugin(UniverRenderEnginePlugin);
univer.registerPlugin(UniverFormulaEnginePlugin);

univer.registerPlugin(UniverUIPlugin, {
  container: 'app',
  footer: false,
});

univer.registerPlugin(UniverDocsPlugin);
univer.registerPlugin(UniverDocsUIPlugin, {
  container: 'univerdoc',
  layout: {
    docContainerConfig: {
      innerLeft: false,
    },
  },
});

univer.createUnit(UniverInstanceType.UNIVER_DOC, {});`

<ReactLive code={code}  />

### 获取文档 Id

```ts
const univerAPI = FUniver.newAPI(univer);
const activeDoc = univerAPI.getActiveDocument()
const unitId = activeDoc?.getId()
```

### 获取文档数据

```ts
const univerAPI = FUniver.newAPI(univer);
const activeDoucment = univerAPI.getActiveDocument()
const saveData = activeDoucment.getSnapshot();
```

或者

```ts
const document = univer.createUniverDoc({});
const saveData = document.save();
```

### 销毁文档

当我们不再需要文档时，可以调用 Univer 实例的 `dispose` 方法来销毁实例。

```ts
univer.dispose();
```


## 文本

对富文本区域的文本元素进行操作

### 插入文本

将指定的文本添加到此文本区域的末尾。

```ts
const univerAPI = FUniver.newAPI(univer)
const activeDoc = univerAPI.getActiveDocument()
activeDoc?.appendText('Univer')
```

### 删除文本

删除光标前的字符

```ts
const univerAPI = FUniver.newAPI(univer)
univerAPI.executeCommand("doc.command.delete-left")
```

删除光标后的字符

```ts
const univerAPI = FUniver.newAPI(univer)
univerAPI.executeCommand("doc.command.delete-right")
```

## 样式

给选中的文本设置字体色

```ts
univerAPI.executeCommand("doc.command.set-inline-format-text-color", {value: "#ff0000"})
```

## 分页符

`\f` 为分页符，用于在文档中插入分页符。

```ts
const univerAPI = FUniver.newAPI(univer)
const activeDoc = univerAPI.getActiveDocument()
activeDoc?.appendText('\f')
```

{/* 选区 */}

## 列表

给光标所在段落添加一个无序列表，重复调用则取消无序列表

```ts
const univerAPI = FUniver.newAPI(univer)
univerAPI.executeCommand("doc.command.list-operation", {listType: 'BULLET_LIST'})
```

给光标所在段落添加一个有序列表，重复调用则取消有序列表

```ts
const univerAPI = FUniver.newAPI(univer)
univerAPI.executeCommand("doc.command.list-operation", {listType: 'ORDER_LIST'})
```

## 参考

更多文档的介绍和 API ，请参考：

- [Univer 文档架构及模块设计](/blog/post/univer-doc-architecture)
- [Univer 文档排版设计初探](/blog/post/doc-typesetting-design)
- [Facade API](/typedoc/@univerjs/facade/README)
